package org.zeapp.opencloud.framework.cloud;

import org.zeapp.opencloud.framework.preference.CallbackHandler;
import org.zeapp.opencloud.framework.preference.Preference;

/**
 * The interface that every driver class must implement. The Cloud framework
 * allows for multiple cloud drivers. Each driver should supply a class that
 * implements the Driver interface. When a Driver class is loaded, it should
 * create an instance of itself and register it with the DriverManager. This
 * means that a user can load and register a driver by calling
 * Class.forName("foo.bah.Driver")
 * 
 * @author Amphiprion
 * 
 */
public interface CloudDriver {
	/**
	 * The driver name displayed to the user.
	 * 
	 * @return the displayed name
	 */
	String getName();

	/**
	 * Retrieves whether the driver thinks that it can provide a cloud service
	 * using the given identifier. So drivers will return true if they
	 * understand the identifier.
	 * 
	 * @param identifier
	 *            the identifier to use
	 * @return true if this driver understands the given identifier; false
	 *         otherwise
	 */
	boolean accepts(String identifier);

	/**
	 * Ask the driver to add its own preference screen to the given UI
	 * Container. As this framework can be used under several systems (java,
	 * android), the UIContainer is not typed.
	 * 
	 * @param UIContainer
	 *            the root container
	 * @param preference
	 *            the preference object used initialize the preference screen.
	 * @param exceptionHandler
	 *            the handler to call when an exception occurs in the preference
	 *            panel
	 */
	void buildPreferenceScreen(Object UIContainer, Preference preference,
			CallbackHandler exceptionHandler);

	/**
	 * Ask the driver to save all preference of its preference screen into the
	 * given Preference object.
	 * 
	 * @param preference
	 *            the preference object used to store this driver preference.
	 * @return true is the operation succeed.
	 */
	boolean applyPreferenceScreenUpdate(Preference preference);

	/**
	 * Return the cloud service managing the given identifier and using the
	 * provided properties
	 * 
	 * @param preference
	 *            the preference to use. (can be null)
	 * @return a Cloud object
	 * @throws CloudException
	 *             if a chunking exception occurs
	 */
	Cloud getCloud(Preference preference) throws CloudException;
}
